​
What are Webhooks?

Webhooks are HTTP-based real-time push notifications sent by Vaultera Switch to your server. They allow immediate communication of payment status and other events, which is critical for:
  • Preventing lost business due to delayed payment confirmation (e.g., bookings or time-sensitive purchases).
  • Avoiding reconciliation issues when payment statuses change (e.g., from “Failed” to “Succeeded”).
  • Improving user experience by triggering immediate fulfillment after payment success.

​
⚙️ Configuring Webhooks

​
1. Create an Endpoint on Your Server

Set up an HTTP or HTTPS endpoint that accepts POST requests. This endpoint will receive webhook notifications from Vaultera Switch, with JSON payloads.

​
2. Register the Webhook URL in Vaultera Switch

Go to your Vaultera Switch Dashboard:
  • Navigate to Developer → Payment Settings
  • Select your Business Profile
  • Under the Webhook Setup section, provide the endpoint URL

​
3. Add Custom HTTP Headers (Optional)

If you want to verify incoming requests with additional security, you can add custom HTTP headers to your webhook. This helps ensure only trusted sources can send requests.
You must provide a valid webhook URL before custom headers can be added.

​
4. Update Vaultera Switch Webhook Endpoints on Connectors

To allow connectors (e.g., Stripe, PayPal) to send updates to Vaultera Switch:
  • Add Vaultera Switch’s webhook endpoints to their dashboards instead of your own.

​
Endpoint format:

EnvironmentEndpoint
Sandboxhttps://api.staging.switch.vaultera.co/webhooks/{merchant_id}/{merchant_connector_id}
Productionhttps://api.switch.vaultera.co/webhooks/{merchant_id}/{merchant_connector_id}
You can also retrieve this from the dashboard under the Processors tab.

​
📬 Webhook Events

You may receive webhooks for the following events: 
payment_succeeded
payment_failed
payment_processing
payment_cancelled
payment_authorized
payment_captured
action_required
refund_succeeded
refund_failed
dispute_opened
dispute_expired
dispute_accepted
dispute_cancelled
dispute_challenged
dispute_won
dispute_lost
mandate_active
mandate_revoked
👉 Click here to view webhook payload structures for each event type.

​
🔐 Webhook Signature Verification

To validate that webhook requests are authentic:

​
Signature Key

When creating a business profile, you can:
  • Provide your own secret via payments_response_hash_key
  • Or let Vaultera Switch generate a secure 64-character key
Ensure this key is stored securely and accessible to your server.

​
Signature Generation (Outgoing Webhook)

  1. JSON encode the webhook payload
  2. Generate an HMAC-SHA512 digest using the payments_response_hash_key
  3. Vaultera Switch includes this as a header: x-webhook-signature-512

​
✅ Validating the Webhook Signature

  1. Retrieve and encode the received payload
  2. Use HMAC-SHA512 with your secret key to compute the signature
  3. Compare with the x-webhook-signature-512 in the header
  4. If they match → the webhook is authentic

​
🧪 Troubleshooting Signature Verification

  • Use the correct header: x-webhook-signature-512 (preferred)
  • Use the right algorithm:
    • For SHA-512: x-webhook-signature-512
    • For SHA-256: x-webhook-signature-256 (fallback)
  • Ensure the payload is unaltered before validation

​
🔁 Webhook Retry Behavior

Vaultera Switch considers a delivery successful only if your server responds with an HTTP 2XX code. If not, webhook retries are attempted for up to 24 hours using exponential backoff:
Retry AttemptDelay
1st1 minute
2nd–3rd5 minutes
4th–8th10 minutes
9th–13th1 hour
14th–16th6 hours
The delay is counted from the previous attempt, not the original delivery time.

​
⚠️ Handling Duplicate Webhooks

Webhook retries may result in duplicate deliveries. To ensure idempotency:
  1. Read the event_id from the webhook payload
  2. Check if it’s already processed (store it in a DB or cache like Redis)
  3. If new → process it; if duplicate → skip it
  4. Retain event_ids for at least 24 hours

​
🕒 Handling Out-of-Order Webhooks

Due to retries and network delays, webhook events may arrive out of order. Use the updated timestamp in the resource payload to determine if the event is more recent than what your system currently holds: 
if updated_timestamp_from_webhook > existing_timestamp_on_record:
    process_event()
else:
    ignore_as_stale()